From 6372a33838ef2cbb06d00063839099d4fa762350 Mon Sep 17 00:00:00 2001
From: Matthias Clasen <mclasen@redhat.com>
Date: Mon, 11 May 2020 00:29:41 -0400
Subject: [PATCH] Clarify docs around focus.

---
 gtk/gtkwidget.c | 30 ++++++++++++++++++++----------
 1 file changed, 20 insertions(+), 10 deletions(-)

diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index a47f05f0c6..0d59aaec6d 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -5047,15 +5047,19 @@ gtk_widget_real_keynav_failed (GtkWidget        *widget,
  * gtk_widget_set_can_focus:
  * @widget: a #GtkWidget
  * @can_focus: whether or not the input focus can enter
- *     the widget tree below @widget
+ *     the widget or any of its children
  *
  * Specifies whether the input focus can enter the widget
- * tree below @widget.
- * 
+ * or any of its children.
+ *
+ * Applications should set @can_focus to %FALSE to mark a
+ * widget as for pointer/touch use only.
+ *
  * Note that having @can_focus be %TRUE is only one of the
  * necessary conditions for being focusable. A widget must
- * also be sensitive and not have an ancestor that is marked
- * as not can-focus in order to receive input focus.
+ * also be sensitive and focusable and not have an ancestor
+ * that is marked as not can-focus in order to receive input
+ * focus.
  *
  * See gtk_widget_grab_focus() for actually setting the input
  * focus on a widget.
@@ -5081,7 +5085,9 @@ gtk_widget_set_can_focus (GtkWidget *widget,
  * gtk_widget_get_can_focus:
  * @widget: a #GtkWidget
  *
- * Determines whether the input focus can enter @widget.
+ * Determines whether the input focus can enter @widget or any
+ * of its children.
+ *
  * See gtk_widget_set_focusable().
  *
  * Returns: %TRUE if the input focus can enter @widget, %FALSE otherwise
@@ -5099,14 +5105,18 @@ gtk_widget_get_can_focus (GtkWidget *widget)
 /**
  * gtk_widget_set_focusable:
  * @widget: a #GtkWidget
- * @focusable: whether or not @widget can own the input focus.
+ * @focusable: whether or not @widget can own the input focus
  *
  * Specifies whether @widget can own the input focus.
- * 
+ *
+ * Widget implementations should set @focusable to %TRUE in
+ * their init() function if they want to receive keyboard input.
+ *
  * Note that having @focusable be %TRUE is only one of the
  * necessary conditions for being focusable. A widget must
- * also be sensitive and not have an ancestor that is marked
- * as not child-focusable in order to receive input focus.
+ * also be sensitive and can-focus and not have an ancestor
+ * that is marked as not can-focus in order to receive input
+ * focus.
  *
  * See gtk_widget_grab_focus() for actually setting the input
  * focus on a widget.
-- 
2.30.2